<?php
/**
 * CMarkdown class file.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
 * @copyright 2008-2013 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

/**
 * CMarkdown converts the captured content from markdown syntax to HTML code.
 *
 * CMarkdown can be used as either a widget or a filter. It is a wrapper of {@link CMarkdownParser}.
 * CMarkdown adds an additional option {@link purifyOutput} which can be set true
 * so that the converted HTML code is purified before being displayed.
 *
 * For details about the markdown syntax, please check the following:
 * <ul>
 * <li>{@link http://daringfireball.net/projects/markdown/syntax official markdown syntax}</li>
 * <li>{@link http://michelf.com/projects/php-markdown/extra/ markdown extra syntax}</li>
 * <li>{@link CMarkdownParser markdown with syntax highlighting}</li>
 * </ul>
 *
 * @property CMarkdownParser $markdownParser The parser instance.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @package system.web.widgets
 * @since 1.0
 */
class CMarkdown extends COutputProcessor
{
    /**
     * @var mixed the CSS file used for the widget. Defaults to null, meaning
     * using the default CSS file included together with the widget.
     * If false, no CSS file will be used. Otherwise, the specified CSS file
     * will be included when using this widget.
     */
    public $cssFile;
    /**
     * @var boolean whether to use {@link CHtmlPurifier} to purify the generated HTML code. Defaults to false.
     */
    public $purifyOutput = false;

    private $_parser;

    /**
     * Processes the captured output.
     * This method converts the content in markdown syntax to HTML code.
     * If {@link purifyOutput} is true, the HTML code will also be purified.
     * @param string $output the captured output to be processed
     * @see convert
     */
    public function processOutput($output)
    {
        $output = $this->transform($output);
        if ($this->purifyOutput) {
            $purifier = new CHtmlPurifier;
            $output = $purifier->purify($output);
        }
        parent::processOutput($output);
    }

    /**
     * Converts the content in markdown syntax to HTML code.
     * This method uses {@link CMarkdownParser} to do the conversion.
     * @param string $output the content to be converted
     * @return string the converted content
     */
    public function transform($output)
    {
        $this->registerClientScript();
        return $this->getMarkdownParser()->transform($output);
    }

    /**
     * Registers the needed CSS and JavaScript.
     */
    public function registerClientScript()
    {
        if ($this->cssFile !== false)
            self::registerCssFile($this->cssFile);
    }

    /**
     * Registers the needed CSS file.
     * @param string $url the CSS URL. If null, a default CSS URL will be used.
     */
    public static function registerCssFile($url = null)
    {
        CTextHighlighter::registerCssFile($url);
    }

    /**
     * Returns the markdown parser instance.
     * This method calls {@link createMarkdownParser} to create the parser instance.
     * Call this method multipe times will only return the same instance.
     * @return CMarkdownParser the parser instance
     */
    public function getMarkdownParser()
    {
        if ($this->_parser === null)
            $this->_parser = $this->createMarkdownParser();
        return $this->_parser;
    }

    /**
     * Creates a markdown parser.
     * By default, this method creates a {@link CMarkdownParser} instance.
     * @return CMarkdownParser the markdown parser.
     */
    protected function createMarkdownParser()
    {
        return new CMarkdownParser;
    }
}
